API designer Experience API

1.1.x
(4 reviews)

Getting Started

This getting started guide shows how to create a project and start working on it.

  1. Get Credentials
  2. Create an API Specification project
  3. List projects
  4. Get the write lock in branch master
  5. Add an API RAML to API Specification project
  6. Add a DataType RAML in a new folder to the API Specification project
  7. List files
  8. Delete Project

1. Get Credentials

To start using the API Designer Experience API it is necessary to be authenticated as it is mandatory to send the token for every operation.

To retrieve this token, a POST request must be made to the endpoint https://anypoint.mulesoft.com/accounts/login with the username and password in the body:

{
  "username": <user>,
  "password": <password>
}

You will need organization-id, owner-id and authorization token credentials to authorize operations against projects.

The organization ID is your organization's unique identifier (UUID), which can be obtained by the organization owner (or any user with Admin privilege) accessing to the Anypoint Platform's Organizations page. For more details on how to obtain the organization ID, please refer to the Access Management API organizations endpoint documentation

The owner ID is your user's unique identifier (UUID), which is NOT related to the username. It can be obtained by the organization owner (or any user with Admin privilege) accessing to the Anypoint Platform's Users page. For more details on how to obtain a given user ID, please refer to the Access Management API users endpoint documentation

For more information on how to retrieve credentials please refer to the Access Management API documentation

2. Create an API Specification project

To create an API Specification project we need to perform a POST operation to the resource /projects (https://anypoint.mulesoft.com/designcenter/api-designer/projects) sending the following data in the request body:

{
    "name": <projectName>,
    "classifier": "raml"
}

The response should be a 201 status returning in the body the id of the new project created.

3. List projects

After creating the project we will perform a GET operation to the /projects resource, to retrieve all the projects the user has permission.

The response should be a 200 status with a list of projects in the response body. The project created in the previous step should be in the list.

4. Get the write lock in branch master

When we want to start working on the project we need to get the write lock over the branch, in order to be able to add files, modify or delete existing ones.

We will use the branch master which is the default one when a project is created. This branch can not be deleted.

To acquire the lock in the branch we need to perform a POST operation to https://anypoint.mulesoft.com/designcenter/api-designer/projects/{project-id}/branches/master/acquireLock, passing branch-name and project-id as URI parameters and sending the body empty.

The response should be a 200 status with the body specifying that the branch is lock and the user owner of the lock.

5. Add an API RAML to API Specification project

To add an API Specification RAML to the project we have to create a new file with the desired raml spec. We will use the following raml:

#%RAML 1.0
title: API Example
version: v1

/ping:
  get:
    responses:
      200:
        body:
          application/json:
            example:
              status: OK

To add the files we need to perform a POST operation to https://anypoint.mulesoft.com/designcenter/api-designer/projects/{project-id}/branches/master/save passing branch-name and project-id as URI parameters and sending in the request body the list of files to add/update. In this case we only want to create one file, so the body should look like this:

[{
  "path": "api.raml",
  "type": "FILE",
  "content": "#%RAML 1.0\ntitle: API Example\nversion: v1\n/ping:\n get:\n  responses: \n   200:\n    body: \n     application/json:\n      example:\n       status: OK",
  "title": "API Spec"
}]

The response should be a 200 status, returning in the response body a list with all the files of the branch.

In this case we will have 4 files, the one that we created and the 3 that are created with the project (.gitignore, {projectName}.raml, exchange.json)

6. Add a DataType RAML in a new folder to the API Specification project

To add a DataType RAML into a new folder, we have to perform the same POST operation that we did in the previous step but in this case with a few diferences in the request body. The path will include a folder called datatypes which will be created alongside the raml file. The body should look like this:

[{
  "path": "datatypes/Car.raml",
  "type": "FILE",
  "content": "#%RAML 1.0 DataType\ntype: object\nproperties:\n  brand: string\n  model: string\n  color: string\n  year?: string",
  "title": "Car Datatype"
}]

The response should be a 200 status, returning in the response body a list with all the files of the branch.

In this case we will have 6 files, the 4 ones that we had in the previous step plus the new raml file (Car.raml) and the new folder(datatypes/).

The file type of for datatypes/ should be FOLDER instead of FILE

7. List files

After adding the files to our project we can list the existing files in the current branch we are working.

To do this we need to perform a GET operation to https://anypoint.mulesoft.com/designcenter/api-designer/projects/{project-id}/branches/master/files

The response should be a 200 status with the response body containing the list of files existing in the branch.

8. Delete Project

We will delete the project once we have finished working with it.

We need to perform a DELETE operation to https://anypoint.mulesoft.com/designcenter/api-designer/projects/{project-id}

The response should be a 204 status.

For more usage examples of the API Designer Experience API check the Usage Examples page.

Reviews